Shareware Super Platinum 8/Shareware Super Platinum 8.iso/mac/PROGTOOL/MULCO303.ZIP;1/MULTICOL.DOC

Text File | 1993-03-20 | 16.3 KB | 338 lines

MULTICOL.DOC
03/20/93

The MULTICOL.EXE program creates multi-columned listings from a text file.  This
listing typically goes to a disk file but it can be routed to a printer or to
the screen instead.  Titles, column headers, and footers are supported.  To a
limited extent, you can use MULTICOL to add headers and footers to regular text
documents as well.

The program also supports the formatted output of ASCII-delimited and dBase
files.

You can also specify that columns of data be totalled as well as having tally
counts generated.


Stored control file:

The routine allows for a number of parameters, most of which can be very long.
To avoid keying all of these in each time, a control file is provided for.  The
control file is designated with the "/Ccontrol_file" parameter and consists
of regular MULTICOL parameters. Every parameter except the /Ccontrol_file
parameter itself is allowed.

The control file provides several benefits for you.  (a) It makes it easier to
enter the same parameters multiple times.  (b) It avoids too-long lines in DOS
(DOS can't handle lines above about 120 characters in length).  (c) It allows
you to store default printer characteristics (one or more sets of them actually)
and bring them in easily.  (d) It allows you to maintain default formats for
your output.

The format for the control statement file is essentially free-form.  Empty lines
and lines which begin with a semi-colon or colon are ignored.  Typically,
parameters begin in column 1 and only one parameter is provided on each line but
this is optional.  For example:

        ; Sample control file for MULTICOL program
        ; This one is for printing wide files (132-columns)
        /DELIM=" ≥ "
        /WIDTH=132
        ; This is the setup string used to set a LaserJet to compressed
        ; portrait mode.
        /SETUP="/027(s16.66H"
        ; Don't want to leave the printer in that mode when you leave.
        /RESET="/027E"
        ; The printer already has pre-defined page lengths so don't
        ; put in page ejects.
        /-EJECT

You can override any of the parameters in the control file from the command line
when you invoke MULTICOL.  (Exception:  If your control card file includes input
and/or output file name specifications, these cannot be overridden from the
command line.)


For ASCII-delimited and dBase input files, you can use MULTICOL to present a
reasonably formatted listing of variables.  A definition file (deffile) is
either read of created for you.  A deffile is used to figure out the
characteristics for each field and also to set certain file characteristics.
The definition file can be created with any text editor.  The definition file
consists of several records with the following fields separated by spaces.
Except for the record type indicator (which must begin in column 1), all other
fields can be placed in any columns:

        (1) record type (see below)
        (2) length of field on input
        (3) number of decimal places for numeric data (if you don't know,
            put a "?" here; for non-numeric data, a "0" is fine) on output
        (4) length of field on output

Any characters after the field length are treated as comment fields.  You would
typically use this to enter the field name or column position or any other
information of use to you.

The data record types accepted by MULTICOL are as follows:

        type C = character data
             N = numeric
             L = logical (T or F)
             D = date (in yyyymmdd format)

Other records accepted in the field definition file are as follows:

        type ; = comment (anything after semi-colon is ignored)
             X = lines to ignore; specify "X=string" and any records
                 which begin with the "string" characters will be ignored;
                 defaults to X="_
             Z = delimiter between fields; defaults to Z=,

The data fields (types C, N, L, and D) should be in the order the fields are
found in the source file.

For dBase files, a deffile will automatically be created for you unless you
specify /USEDEF.  In that case, the routine will read the deffile and act
appropriately.  This is necessary if you want fields expanded or ignored.

You can also use the /PRINT specification to select which files you want
printed.

For adding headers and footers to regular text files, make sure you specify
/COLUMNS=1.  The system starts a new page when it runs into lines with page
eject characters or when it hits the number of lines specified in the /LINE=n
parameter.  (The page eject part is only true if /-WRAP is in effect.)


Syntax:

    MULTICOL infile outfile [ /OVERWRITE | /-OVERWRITE | /OVERASK ]
      [ /DELIM="string" ]
      [ /LINES=n ] [ /WIDTH=n ] [ /EJECT | /-EJECT ]
      [ /COLUMNS=n ] [ /WRAP | /-WRAP [ /INDENT=n ] | /REFLOW ]
      [ /Ccontrol_file ] [ /SETUP="string" ] [ /RESET="string" ]
      [ /{ TITLE | HEADER | FOOTER }[ R | C | L ][ 1 to 5]="text" ]
      [ /{ TITLE | HEADER | FOOTER }{ T | B }="string" ]
      [ /FROM ASCII | /FROM ASCII=char | /FROM DBF ] [ /DEF=deffile ]
      [ /SKIP | /MISSING | /ABORT ] [ /GAP=n ] [ /USEDEF ] [ /TALLY ]
      [ /SUM={ col_spec | var_spec } ] [ /BREAK={ col_spec | var_spec } ]
      [ /PRINT={ col_spec | var_spec } ] [ /? ]

where:

"infile" is the name of the ASCII text file that you want reformatted into a
multicolumn file.

"outfile" is the name of the ASCII text file that you want to create.  "infile"
and "outfile" cannot be the same.  While "outfile" is typically a file name, you
can specify devices like "PRN:" or "SCRN:" if you want to.

"/OVERWRITE" says to write over the outfile if it already exists.

"/-OVERWRITE" says to abort if the outfile exists already.

"/OVERASK" says to prompt if the outfile exists already.  This is the default.

"/DELIM="string"" indicates the character string that should be used to separate
columns.  Note that the string itself must appear within quotation marks.  By
default, the string is " | ".

"/LINES=n" indicates how many physical lines can fit on your printed page.
Defaults to /LINES=60.

"/WIDTH=n" indicates how many physical characters can fit on your printed page.
Defaults to /WIDTH=80.  Typically, if you are in compressed mode, the value is
/WIDTH=132.

"/EJECT" says to add a page eject after the maximum lines-per-page (/LINES=n)
setting.  This is not recommended if you're using a printer with a defined page
size that is the the same or smaller than the /LINES=n setting.  If you're using
something like a LaserJet, setting /EJECT will typically result in blank pages
being generated after each full page.  The default is "/-EJECT".

"/-EJECT" is the opposite of "/EJECT".  This is the default.


"/COLUMNS=n" indicates how many text columns you want to appear.  The value can
be as low as one (useful if you're just doing reformatting of paragraphs).
There's no maximum value but anything above 7 or so starts looking worthless.
The default value is /COLUMNS=2.

The combination of the /COLUMNS=n, /DELIM="string", and /WIDTH=n tells the
program how wide each physical column is.  For example, using the defaults of
/COLUMNS=2, /DELIM=" | ", and /WIDTH=80, each text column is a maximum of 38
characters.  (Width - (Size of Delimiter * (Number of columns - 1), all divided
by 2.  INT((80-(3*1))/2) is 38.) The routine tells you what column size it
picked; if you don't like the result, adjust some of your other parameters and
try it again.

"/WRAP", "/-WRAP", and "/REFLOW" tells the program what you want it to do with
text that exceeds the width of each physical column.  The default is /-WRAP.
Each is explained separately below:

"/-WRAP" indicates that long lines are to be truncated and the excess characters
are lost.  This is the default.

"/WRAP" says the line is to be parsed into words and any word(s) that doesn't
fit on the original line spills over on successive line(s).  The spillover lines
are indented by the value of "/INDENT=n".  By default, the secondary lines are
indented by 2 spaces.

"/REFLOW" is the most sophisticated of the options.  /REFLOW will treat most of
the text as paragraphs are readjust the length of the entire paragraph.  The
reflowing stops whenever a new paragraph is detected.  The routine considers a
new paragraph to start whenever the succeeding line is either blank or it starts
with a space.  Unlike with the other options, you can actually end up with fewer
lines in your output file than you had in your input file using /REFLOW.  This
only happens of course if the source lines were generally shorter than the
computer text column width.

"/Ccontrol_file" specifies an external text file that contains control
statements.  See the discussion above about control files.

"/SETUP="string"" specifies the initialization string to put at the beginning of
the file.  This is typically used to make sure your printer has the proper
orientation (landscape vs portrait), characters per inch (cpi), and lines per
inch (lpi) settings before printing.  The setup string itself must appear in
quotation marks.  Use "/027" for the Escape character and any other ASCII code
can be entered with "/" followed by its 3-digit value (e.g.  "/032" is a space).
You have to know your own setup strings.  Borland's documentation provides some
very useful tables for this sort of thing.  For an HP LaserJet, the setups I use
all of the time are:

        Orientation     PageLen RMargin String

        Portrait        60      80      /027E
        Portrait        60      132     /027(s16.66H
        Landscape       45      106     /027&l10
        Landscape       45      176     /027&l10/027(s16.66H
        Landscape       66      106     /027&l1o5.45C
        Landscape       66      176     /027&l1o5.45C/027(s16.66H


"/RESET="string"" specifies the string to send after your file is done.  This
typically resets the printer to its system default setting so you won't get
stuck in landscape mode forever.  The setup string itself must appear in
quotation marks.  Use "/027" for the Escape character.  For an HP LaserJet, the
following resets the printer to its factory settings:

        /027E

"/{ TITLE | HEADER | FOOTER } [ R | C | L ] [ 1 to 5 ]="text"" allows you to
specify up to 5 lines each for the report's TITLE (at the top of each page),
HEADER (at the top of each column), and FOOTER (at the bottom of each page).
You can specify positioning as well:

        R = right-justify the text
        C = center the text (this is the default for /TITLE and /HEADER)
        L = left-justify the text (this is the default for /FOOTER)

If no line number is specified, line 1 is presumed.  If a line number is
specified, all lines before that number are presumed to contain something and
will be blank filled if you don't provide anything.  If, for example, you
specify "/TITLER3="Hi!"", without specifying any other titles, then you'll get
blank lines for /TITLE1 and /TITLE2, but you won't get any /TITLE4 or /TITLE5.

The text itself can contain one of six imbedded string-replacement codes:

        ^B will be replaced by the page number
        ^D will be replaced by today's date (in mm/dd/yy form)
        ^T will be replaced by today's time (in hh:mm form)
        ^N will be replaced by the input file's name
        ^A will be replaced by the input file's creation date (mm/dd/yy form)
        ^I will be replaced by the input file's creation time (hh:mm form)

"/{TITLE | HEADER | FOOTER }{ T | B }="string"" allows you to specify a
repeating string to be placed either on top of or on the bottom of your titles,
headers, and footers.  The string, typically consisting of just a few
characters, is repeated by the routine until it fills up the available space.
For example, "/TITLET=" -"" would add the following line at the top of the
report:

 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

This option is typically used to (a) insure that there are blank lines before
footer lines and (b) to have demarcations between sections.

"/FROM ASCII" says that the input file is ASCII-delimited (with quotes around
strings and commas between fields).  Alternatively, you can specify that the
file is "/FROM ASCII=char" and the "char" character will be used as a delimiter
between fields instead of a comma.  The routine will require that a deffile
(/DEF=defile) be specified with the definition of fields.

"/FROM DBF" specifies that the input file is a dBase file.  If the file
extension is .DBF, the routine will presume this.  The routine uses dBase's
default field lengths unless /USEDEF is specified along with /DEF=deffile.

"/DEF=deffile" provides the name of the definition file for ASCII-delimited and
some dBase input files.  A description of the definition file was given
previously.


"/SKIP" says to skip ASCII-delimited records with bad data values; otherwise the
routine aborts when it runs into any.  /SKIP, /MISSING, and /ABORT are mutually
exclusive.

"/MISSING" says to presume any missing fields in an ASCII-delimited record
should be filled in with blanks (for character fields) and 0 for numeric fields.
Incomplete records are written out (unlike in /SKIP).  /SKIP, /MISSING, and
/ABORT are mutually exclusive.

"/ABORT" says to abort when you run into bad records.  This is typically the
default.  /SKIP, /MISSING, and /ABORT are mutually exclusive.

"/GAP=n" is used when printing ASCII-delimited or dBase files.  It tells the
program how many spaces to print between each variable.  The default is /GAP=2.

"/USEDEF" is specified for dBase input files if you want MULTICOL to read an
existing field-definition file.  Since dBase files contain all of the field
information in the data base itself, MULTICOL will normally pick up all field
information from there and simply ignore any field-definition file.

"/TALLY" says to present a count of items.  If a /BREAK specification is
provided, there will be a tally for each break as well as for the grand total.


"/SUM={ col_spec | var_spec }" says to summarize (add) all values in particular
columns.  If ASCII-delimited or dBase input is used, you can specify variables
to be added.  If a /BREAK specification is provided, there will be subtotals at
each break as well as grand total.

The "col_spec | var_spec" portion expands to "{ Cx[-x] | Vx[-x] } [, {Cx[-x] |
Vx[-x] } ]..." where "x" is the column or variable number, "-" indicates a
range, and "C" means column whereas "V" means variable.  If you have an
ASCII-delimited file and you want the values of the first three variables
summarized, you'd say "/SUM=C1-3".  If you want variables 2, and 4 through 6
summarized, you'd say "/SUM=C2,C4-6".  If you want the values in columns 10
through 20 summarized, you'd say "/SUM=C10-20".  Note that for column
specifications, you have to request the output columns, not input columns.

"/BREAK={ col_spec | var_spec }" says to present tally, total, or blank lines
based on the values in certain columns or variables.  For example, if you had an
alphabetical listing and you wanted to, you could break up the listing by the
first letter of the last name.  A break is generated whenever there is a change
in any character in the column or variable range specified.  The
"col_spec | var_spec" specification is identical to the /SUM specification.

"/PRINT={ col_spec | var_spec }" says to print only some of the fields.  For
example, if you have a dBase file with 10 variables and you only want some of
them to print out, you can say "/PRINT=V1-3,V6,V8" or something like that.  Note
that the /PRINT specification works in conjunction with any 0-length output
specifications in the deffile.

"/?" or "/HELP" or "HELP" gives you syntactical help.


This program was written by Bruce Guthrie of Wayne Software.  It is free for use
provided relevant documentation is kept with the program, no changes are made to
the program or documentation, and it is not bundled with commercial programs or
charged for separately.  People who need to bundle it in for-sale packages must
pay a $50 registration fee to "Wayne Software" at the following address.
Comments and suggestions can also be sent to:

                Bruce Guthrie
                Wayne Software
                113 Sheffield St.
                Silver Spring, MD 20910

                fax: [phone]